{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Tutorial - Optimization Problem\n",
    "---\n",
    "This tutorial will study some certain cases.  All of them can be viewed as searching groundstate(s) of some Hamiltonian."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Ising model"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Definition of the problem\n",
    "\n",
    "A $3\\times 3$ spin lattice is governed the Hamiltonian \n",
    "\n",
    "$$ H = \\sum_{\\mbox{i and j are neighbors}}Z_iZ_j .$$\n",
    "\n",
    "The aim is to find out the spin configuration to minimize the Hamiltonian. No periodic boundary in this case."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Map the problem\n",
    "\n",
    "The key is to set a proper connection on a _phalanx_ annealer."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "from phalanx import Annealer\n",
    "\n",
    "beta = 10.  # A large beta can highlight the groundstate.\n",
    "num_qubits = 9\n",
    "ism = Annealer(beta, num_qubits)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "On this $3\\times 3$ lattice, we use qubit 0~8 to denote each spin.  For example, 3 corresponds to the spin in the second row and the first column.  From the Hamiltonian, we can infer its connection."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "connection = [\n",
    "    [0,1,0,1,0,0,0,0,0],\n",
    "    [0,0,1,0,1,0,0,0,0],\n",
    "    [0,0,0,0,0,1,0,0,0],\n",
    "    [0,0,0,0,1,0,1,0,0],\n",
    "    [0,0,0,0,0,1,0,1,0],\n",
    "    [0,0,0,0,0,0,0,0,1],\n",
    "    [0,0,0,0,0,0,0,1,0],\n",
    "    [0,0,0,0,0,0,0,0,1],\n",
    "    [0,0,0,0,0,0,0,0,0],\n",
    "]\n",
    "ism.set_connection(connection)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "check the connection of spins."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "image/png": "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\n",
      "text/plain": [
       "<Figure size 432x288 with 1 Axes>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "ism.draw_topology()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### The spin configurtion minimize the Hamiltonian\n",
    "\n",
    "After an annealing process, the Ising model should be captured as groundstate with a high probability."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "measurement 0: [1, -1, 1, -1, 1, -1, 1, -1, 1]\n",
      "measurement 1: [-1, 1, -1, 1, -1, 1, -1, 1, -1]\n",
      "measurement 2: [-1, 1, -1, 1, -1, 1, -1, 1, -1]\n",
      "measurement 3: [-1, 1, -1, 1, -1, 1, -1, 1, -1]\n",
      "measurement 4: [-1, 1, -1, 1, -1, 1, -1, 1, -1]\n",
      "measurement 5: [-1, 1, -1, 1, -1, 1, -1, 1, -1]\n",
      "measurement 6: [1, -1, 1, -1, 1, -1, 1, -1, 1]\n",
      "measurement 7: [1, -1, 1, -1, 1, -1, 1, -1, 1]\n",
      "measurement 8: [1, -1, 1, -1, 1, -1, 1, -1, 1]\n",
      "measurement 9: [1, -1, 1, -1, 1, -1, 1, -1, 1]\n",
      "measurement 10: [-1, 1, -1, 1, -1, 1, -1, 1, -1]\n",
      "measurement 11: [-1, 1, -1, 1, -1, 1, -1, 1, -1]\n",
      "measurement 12: [1, -1, 1, -1, 1, -1, 1, -1, 1]\n",
      "measurement 13: [1, -1, 1, -1, 1, -1, 1, -1, 1]\n",
      "measurement 14: [-1, 1, -1, 1, -1, 1, -1, 1, -1]\n",
      "measurement 15: [1, -1, 1, -1, 1, -1, 1, -1, 1]\n",
      "measurement 16: [-1, 1, -1, 1, -1, 1, -1, 1, -1]\n",
      "measurement 17: [-1, 1, -1, 1, -1, 1, -1, 1, -1]\n",
      "measurement 18: [-1, 1, -1, 1, -1, 1, -1, 1, -1]\n",
      "measurement 19: [1, -1, 1, -1, 1, -1, 1, -1, 1]\n"
     ]
    }
   ],
   "source": [
    "for i in range(20):\n",
    "    print('measurement '+str(i)+':', ism.measure())"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Obviously, there are 2 configurations minimize the Ising model.  We show the last case in a graph."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "image/png": "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5olfzQoE162ET3nrHykBEBcXx8CBA/H29mbp0qV29cEkiq+UlBReffVV4uPjWbt2LYGBgWpHKrBDhw4xYsQIqlatysKFC6lbN39Pfxelw507d+jfvz+ZmZmsW7euZH62KnZMr9crH374oeLl5aWsWrVKMZvNakcSdmznzp1KjRo1lLFjxyrZ2dlqxylUer1e+fTTT5WKFSsqM2bMUPR6vdqRRDG0d+9epXr16so777xTon9HbNLxFbXo6GgGDhxInTp1WLx4MT4+PmpHEnYkLy+PSZMmsW7dOiIiInj88cfVjmQzly5dYuTIkVy9epXFixfzyCOPqB1JFANms/nBIq6IiAieeuoptSPZVIlYGhkUFMSxY8fw8/MjMDCQ9evXqx1J2Im4uDhCQkJISEjgxIkTJbroAdSpU4dt27YxefJk+vTpw4gRI0hNTVU7llDRnTt36NatG99//z3Hjh0r8UUPSkjhA3B2dmbatGls3bqVKVOm0KdPH5KTk9WOJYops9nMvHnz6NixI6+//jrffPMNlSpVUjtWkdBoNDz//POcOnUKBwcHfH19+eqrr2TxSym0f/9+goODCQwMZM+ePdSoUUPtSEWiREx1/llOTg7vv/8+//3vf1m4cCG9evVSO5IoRm7evMmgQYPIyMjgyy+/pF69empHUtWRI0cYPnw4Pj4+LFy4sNT/36M0MJvNzJw5k7lz55aKqc0/KzEd3x+5uroya9YsNmzYwPjx4+nfv79M5wgANm3aRHBwMI888gj79u2TD3mgVatWREZG8thjj9GqVSumT5+OXq9XO5awkeTkZLp168bWrVtLzdTmn5XIwve7du3aERMTQ/ny5fH39+fHH39UO5JQyb179xgyZAgTJkxg8+bNfPDBByXqvqSCcnR0ZPz48URGRnLgwAGCgoLYv3+/2rFEIft9ajMgIKBUTW3+haprSovQzp07lVq1ailDhgxR0tPT1Y4jitDBgweVunXrKkOHDlXu3bundpxiz2w2Kxs3blSqVq2qDBs2TLl7967akUQBmUwm5ZNPPlG8vb2V77//Xu04qivRHd8fderUidjYWLRaLQEBAezcuVPtSMLGDAYDkydP5plnniEsLIylS5dSrlw5tWMVexqNhueee45Tp07h5OSEr68v//3vf2Xxi51KTk7m6aefZsuWLURGRtKtWze1I6muRC5u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\n",
      "text/plain": [
       "<Figure size 432x288 with 1 Axes>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "ism.draw_result()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Quadratic binary value functions\n",
    "\n",
    "If a quadratic function lives on the domain $\\{0,1\\}$, _phalanx_ can easily find out its minimum."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Problem\n",
    "\n",
    "$$ f = a + b - c \\times d $$\n",
    "\n",
    "$ a,b,c $ and $d$ can either be $0$ or $1$.  The aim is to find an solution to minimize $f$."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Map the problem to an Ising type\n",
    "\n",
    "By a transformation\n",
    "\n",
    "$$ s = 2q - 1 $$ \n",
    "\n",
    "We can transform $ a,b,c,d $ to $a',b',c',d'$ on the domain $\\{-1, 1\\}$, then the $f$ comes to an equivalent problem\n",
    "\n",
    "\\begin{align*}\n",
    "f' &= \\frac{a'+1}{2} + \\frac{b'+1}{2} - \\frac{c'+1}{2} \\times \\frac{d'+1}{2} \\\\\n",
    "  &= \\frac{a'+b'}{2} - \\frac{c'd'+c'+d'}{4} - 0.75\n",
    "\\end{align*}\n",
    " \n",
    "We just need to minimize $\\frac{a'+b'}{2} - \\frac{c'd'+c'+d'}{4}$. This can be viewed as an Ising model Hamiltonian.  We fetch 4 qubits to play as the variables, the connection matrix can be set according to the Hamiltonian."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [],
   "source": [
    "beta = 10.\n",
    "num_qubits = 4\n",
    "qbvf = Annealer(beta, num_qubits)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [],
   "source": [
    "connection = [\n",
    "    [0.5, 0,   0,     0    ],\n",
    "    [0,   0.5, 0,     0    ],\n",
    "    [0,   0,   -0.25, -0.25],\n",
    "    [0,   0,   0,     -0.25]\n",
    "]\n",
    "qbvf.set_connection(connection)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Find solution with measurements"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "measurement 0: [-1, -1, 1, 1]\n",
      "measurement 1: [-1, -1, 1, 1]\n",
      "measurement 2: [-1, -1, 1, 1]\n",
      "measurement 3: [-1, -1, 1, 1]\n"
     ]
    }
   ],
   "source": [
    "for i in range(4):\n",
    "    print('measurement '+str(i)+':', qbvf.measure())"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This means $[-1, -1, 1, 1]$ is the point of minimum of $f'$.  By the same transformation, the solution for the original problem $f$ is\n",
    "\n",
    "$$ [0, 0, 1, 1] $$\n",
    "\n",
    "which corresponds to the minimum $f=-1$."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Boolean functions"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### AND gate\n",
    "\n",
    "AND gate returns a binary number from two binary inputs.  Its truth table is \n",
    "\n",
    "| a  | b  | OUT  |\n",
    "| :--: | :--: | :--: |\n",
    "|  0   |  0   |  0   |\n",
    "|  0   |  1   |  0   |\n",
    "|  1   |  0   |  0   |\n",
    "|  1   |  1   |  1   |\n",
    "\n",
    "The aim is to show how to use an annealing process to express this function.  "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Expression\n",
    "\n",
    "First, we fetch 2 qubits $q_1$ and $q_2$, then define such a quadratic binary value function\n",
    "\n",
    "$$ f = aq_1 + q_2 - 4abq_1q_2 $$\n",
    "\n",
    "$a,b$ are two input values of the AND gate. Since we use 1 and 0 represent qubit states, this function will lead the annealing outcome of $q_2$ as the the output of the AND gate. To see this, we write down the equivalent Hamiltonian for this function with the transformation $s = 2q-1$,\n",
    "\n",
    "$$ H = (\\frac{a}{2}-ab)s_1 + (\\frac{1}{2}-ab)s_2 - abs_1s_2 $$\n",
    "\n",
    "Here $s_1, s_2$ can be $1$ or $-1$. So the connection matrix is \n",
    "\n",
    "\\begin{bmatrix}\n",
    "\\frac{a}{2}-ab & -ab \\\\\n",
    "0 & \\frac{1}{2}-ab\n",
    "\\end{bmatrix}\n",
    "\n",
    "Let's try it with our simulator."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [],
   "source": [
    "beta = 10.\n",
    "num_qubits = 2\n",
    "and_gate = Annealer(beta, num_qubits)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### For $a=0,b=0$"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "0.0"
      ]
     },
     "execution_count": 10,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "connection = [\n",
    "    [0,0],\n",
    "    [0,0.5]\n",
    "]\n",
    "and_gate.set_connection(connection)\n",
    "\n",
    "(and_gate.measure()[1] + 1) / 2"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### For $a=0,b=1$"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "0.0"
      ]
     },
     "execution_count": 11,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "connection = [\n",
    "    [0,0],\n",
    "    [0,0.5]\n",
    "]\n",
    "and_gate.set_connection(connection)\n",
    "\n",
    "(and_gate.measure()[1] + 1) / 2"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### For $a=1,b=0$"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "0.0"
      ]
     },
     "execution_count": 12,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "connection = [\n",
    "    [0.5,0],\n",
    "    [0,0.5]\n",
    "]\n",
    "and_gate.set_connection(connection)\n",
    "\n",
    "(and_gate.measure()[1] + 1) / 2"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### For $a=1,b=1$"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "1.0"
      ]
     },
     "execution_count": 13,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "connection = [\n",
    "    [-0.5,-1],\n",
    "    [0,-0.5]\n",
    "]\n",
    "and_gate.set_connection(connection)\n",
    "\n",
    "(and_gate.measure()[1] + 1) / 2"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "So we successfully build an classical AND gate with our quantum annealer."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.7.9"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}
